[% setvar title subroutine / generic entity documentation %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>subroutine / generic entity documentation</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Michael Maraist &lt;<a href='mailto:maraist@udel.edu'>maraist@udel.edu</a>&gt;
  Date: 25 Aug 2000
  Last Modified: 25 Sep 2000
  Mailing List: <a href='mailto:perl6-language@perl.org'>perl6-language@perl.org</a>
  Number: 176
  Version: 2
  Status: Frozen</pre>
<a name='CHANGES'></a><h1>CHANGES</h1>
<p>Resolved that attributes can already allow functional parameters, and thus
removed it's discussion.</p>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Extend perl's self documentation to allow dynamic documentation with at
least as much power as &quot;perldoc -f xxxx&quot;.  Ideally, documentation would be
an attribute and therefore retrievable at run time.</p>
<pre> #File: Foo.pm
 sub foo : doc( &lt;&lt;EOS )
   Function:  Foo
   In:    scalar - int - foo identifier
   Out:    array - decomposed foo
   Effects: Queries Foo DB
   Exceptions: DBI, &quot;bad foo id&quot;
 EOS
 {
   # Do good foo
   ...
 } # end foo

 #File: main.pl
 use Foo;

 print &quot;Foo Info: &quot;, attributes::doc::get( \&amp;Foo::foo ), &quot;\n&quot;;

 # Command prompt
 % perldoc -f Foo::foo</pre>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<a name='Motivation'></a><h2>Motivation</h2>
<p>Many interpreted languages allow run-time querying of information about a
function.  Lisp, python, matlab, etc.  Recently, even byte-compiled
languages, such as Java are even applying function-based documentation.
Perl, in comparison, has a very functional POD format, but unfortunately, it
is flat, static, and only useful at the level of a module.  The only real
advantage that POD servers is in the keeping of documentation close to the
code.  Though various tools exist to dynamically generate documentation on
functions (I have written a few simple ones), perl code is not easily
analyzable.</p>
<p>Java, for example, has many attributes associated with a function: name,
return type, parameter types, throwable exceptions, and class heirarchy.
This allows javadoc to produce a comprehensive suite of documents even from
compiled code, without a single explicit comment.  Document comments ( /**
... **/ ) are also intelligently associated with the function to complete
the process.</p>
<p>Perl doesn't really stand a chance at this level of sophistication (being,
for the most part, a type-less language with little or no useful function pr
ototyping).</p>
<p>At the other extreme are the interpreted languages.  Since you are at the
prompt for much of the development process in these languages, it is
obviously useful to have a &quot;reflection&quot;, or the ability to query information
about pre-defined components.  The first bare string after the function
header is usually considered the function-comment.  Various languages, such
as Python, have perl-like HERE-DOCUMENTS, so this works out nicely.</p>
<p>Perl is somewhere in between.  It was designed to work more like a compiled
language (so the reflection property isn't really necessary), but has a very
powerful interpretive debugger in which many developers, like myself, keep
open like a prompt.  This begs for an ability to perform quick-and-dirty
queries about the nature of a given function.  It would be a very cool and
perl-like enhancement.</p>
<a name='Requirements'></a><h2>Requirements</h2>
<p>At a minimum, documentation should be able to be associated with a function.
I propose some derivative of the 'attributes' pragma for storing this
information.  As it stands, attributes is keyword presence based, so it
probably would not be a good candidate for document storage out of the box.
A sub-pragma ( read sub-module ) could take as it's only argument a scalar
string as in:</p>
<pre> sub foo {
   use attributes::doc &quot;This is my documentation&quot;;
 } # end foo

 sub foo {
   use attributes::doc &lt;&lt;EOS;
 Multi-line
 Comment
 EOS
 } # end foo</pre>
<p>Or even possibly using newer style:</p>
<pre> use attributes;

 sub foo : doc( &lt;&lt;EOS )
 Multi-line
 Comment
 EOS
 {
 ...
 } # end foo

 print attributes::getDoc( \&amp;foo );</pre>
<p>Assuming the newer attributes style ( symbol: attribute-list ) is feasible ,
then documentation could be applied to any perl-entity.  As in:</p>
<pre> package Foo : doc( &quot;Simple collection of Foo material&quot; );

 sub foo : doc( &quot;analyzes a foo ID&quot; ) {
   my ( $x, $y, $z ) : doc( &quot;temp variables to store mathematical
calculations&quot; );
 } # end foo

 our %cache : doc( &quot;Store DB accesses to foo&quot; );</pre>
<p>After association of text with a function, the next problem is in how to
retrieve it.  There is already the attributes::get( {func-ref} ), so it
should be trivial to apply attributes::doc::get( {func-ref} ).  I am not up
to speed on how perldoc -f {func-name} works, but I don't see any major
problem with extending it to perform the appropriate get and print
statements.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>The simplest implementation would be to create the independant module
attributes::doc, and perform a &quot;use attributes::doc 'str'&quot;.  The import
routine would get the calling function's name, and apply the documentation
to a global hash.  The get function would simply query this hash.  The
perldoc program would also have to add a search for this.</p>
<p>The more desired approach is to make 'doc' a full fledged attribute, and
provide
the accessor function in the &quot;attributes&quot; module as for
attributes::doc::get( {func-ref} ).</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>perldoc attrs</p>
<p>perldoc attributes</p>
<p>RFC 160: Function-call named parameters (with compiler optimizations)</p>
</div>
